package OddMuse;

=head1 NAME

OddMuse::Database::SmartTitles

=cut

=head1 DESCRIPTION

Every HTML page has a title which is, for example, shown as the window title of
the browser, used as a link description when you bookmark a page and, most
importantly, used to identify pages in search engines results.

For these reasons it is important to have a good (meaningful and descriptive)
title for a page. Most wiki engines use WikiNames as page titles. Since
WikiNames can be difficult to read and meaningless for search engines, this
module gives you the ability to define a Smart Title, for each page on your
wiki.  Further, it also defines a Subtitle, which can be used to provide a
'tagline' for the page.  Enabling this module will not affect page rendering in
any *unless you use the functions created by this module.

Credit for this idea comes from the Wikka Wiki engine.

=cut

$VERSION = ( q$Revision: 40 $ ) =~ /(\d+)/g;
use strict;

=head1 SYNOPSIS

Somewhere in the body of your text, on it’s own line, insert something like this.

  #TITLE A Nice Long Title

and optionally

  #SUBTITLE This page is about something and something

The module will scrape “A Nice Long Title”, eliminate it from the textflow, and
insert it in the html <title> attribute and into your <h1> attribute in the
header area.

=head1 RULES

=over 4

=item * StripTitlesRule

This rule simply strips out any instances of #TITLE ... from the html text
rendered to the browser.

=cut

push( @MyRules, \&StripTitlesRule );

sub StripTitlesRule {
    if ( m/\G#TITLE[ \t]+(.*?)\s*\n+/cg ) {
      return undef;
    }
  return undef;
}

=item * StripSubTitlesRule

This rule simply strips out any instances of #SUBTITLE ... from the html text
rendered to the browser.

=cut

push( @MyRules, \&StripSubTitlesRule );

sub StripSubTitlesRule {
    if ( m/\G#SUBTITLE[ \t]+(.*?)\s*\n+/cg ) {
      return undef;
    }
  return undef;
}

=back

=head1 FUNCTIONS

=over 4

=item * NewSmartGetHeader

This module is appended to the OddMuse GetHeader function, and modifies the
header returned to the browser with a proper H1 and TITLE attribute.  In
addition, if a SUBTITLE is defined, in outputs it as a part of the header as
a paragraph with a class name of 'subtitle'.

=cut

*OldSmartGetHeader = *GetHeader;
*GetHeader         = *SmartGetHeader;

sub SmartGetHeader {
    my ( $id, $title, $oldId, $nocache, $status, $rev ) = @_;
    my $header = OldSmartGetHeader( @_ );
    $title = NormalToFree( $title );

  return $header unless $id;
    OpenPage( $id );

    my ( $smarttitle ) = ( $Page{ text } =~ /\#TITLE[ \t]+(.*?)\s*\n+/ );

    if ( $smarttitle ) {
        my $OldTitle = '<title>' . $SiteName . ': ' . $title . '</title>';
        my $NewTitle = '<title>' . $SiteName . ': ' . $smarttitle . '</title>';
        $header =~ s/$OldTitle/$NewTitle/;

        my $OldGetHtmlHeader = '>' . $title . '</a>';
        my $NewGetHtmlHeader = '>' . $smarttitle . '</a>';
        $header =~ s/$OldGetHtmlHeader/$NewGetHtmlHeader/g;

    } ## end if ( $smarttitle )

    my ( $subtitle ) = ( $Page{ text } =~ m/\#SUBTITLE[ \t]+(.*?)\s*\n+/ );

    if ( $subtitle ) {
        my $OldSubGetHtmlHeader = '</a></h1>';
        my $NewSubGetHtmlHeader =
          '</a></h1><p class="subtitle">' . $subtitle . '</p>';
        $header =~ s/$OldSubGetHtmlHeader/$NewSubGetHtmlHeader/g;
    }
  return $header;
} ## end sub SmartGetHeader

1;

__END__

=back

=head1 CSS

=over 4

=item * p.subtitle

Paragraph which contains the subtitle. (if any)

=back

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to C<cmauch@gmail.com>

=head1 AUTHOR

Charles Mauch <cmauch@gmail.com>

=head1 LICENSE

Copyright (c) 2006 Charles Mauch

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

=head1 SEE ALSO

perl(1).

=cut

# $Id: SmartTitles.pm 40 2006-10-01 04:11:44Z cmauch $
